#! /bin/sh -e
## 10_update_docs.dpatch by Daniel Kobras <kobras@debian.org>
##
## All lines beginning with `## DP:' are a description of the patch.
## DP: Update documentation of API functions.
## DP: Pull from upstream BK tree.

if [ $# -lt 1 ]; then
    echo "`basename $0`: script expects -patch|-unpatch as argument" >&2
    exit 1
fi

[ -f debian/patches/00patch-opts ] && . debian/patches/00patch-opts
patch_opts="${patch_opts:--f --no-backup-if-mismatch} ${2:+-d $2}"

case "$1" in
    -patch) patch -p1 ${patch_opts} < $0;;
    -unpatch) patch -R -p1 ${patch_opts} < $0;;
    *)
        echo "`basename $0`: script expects -patch|-unpatch as argument" >&2
        exit 1;;
esac

exit 0

@DPATCH@
# This is a BitKeeper generated diff -Nru style patch.
#
# ChangeSet
#   2004/03/29 21:34:37-08:00 michael@holy-joe.68k.org 
#   Update documentation.
# 
# ChangeLog
#   2004/03/29 21:34:03-08:00 michael@holy-joe.68k.org +4 -0
#   Update documentation.
# 
# docs/afGetFrameSize
#   2004/03/29 21:29:03-08:00 michael@holy-joe.68k.org +9 -8
#   Update documentation.
# 
# docs/afIntro
#   2004/03/29 21:29:11-08:00 michael@holy-joe.68k.org +2 -2
#   Update documentation.
# 
# docs/afReadFrames
#   2004/03/29 21:29:28-08:00 michael@holy-joe.68k.org +0 -5
#   Update documentation.
# 
# docs/afSetVirtualByteOrder
#   2004/03/29 21:31:23-08:00 michael@holy-joe.68k.org +1 -3
#   Update documentation.
# 
diff -Nru a/docs/afGetFrameSize b/docs/afGetFrameSize
--- a/docs/afGetFrameSize	2004-06-14 03:29:27 -07:00
+++ b/docs/afGetFrameSize	2004-06-14 03:29:27 -07:00
@@ -14,12 +14,9 @@
 one audio track within a file, so track should always be
 AF_DEFAULT_TRACK.
 
-If expand3to4 is a non-zero value, then 3-byte frames will be treated
-as taking up 4 bytes in memory.  This is useful for calculating how
-much memory will be needed to store audio data suitable for playback
-since 24-bit audio data is typically aligned on 32-bit boundaries.  (At
-least that's how it's done on SGI systems; I know of no other computer
-system that has support for 24-bit audio.)
+expand3to4 is a boolean-valued integer indicating whether frame size
+calculation will treat 24-bit data as having a size of 3 bytes or 4
+bytes.
 
 DESCRIPTION
 afGetFrameSize returns the number of bytes in a frame in the given
@@ -30,5 +27,9 @@
 track, a sample frame will always contain two samples, one for the left
 channel and one for the right channel.
 
-The parameter expand3to4 is ignored unless the specified audio track
-contains 24-bit sampled audio data.
+A non-zero value of expand3to4 should be used when calculating the
+frame size for storage in memory (since 24-bit audio data is presented
+in memory as a 4-byte sign-extended integer), while a value of zero
+should be used for calculating storage on disk where no padding is
+added.  The parameter expand3to4 is ignored unless the specified audio
+track contains 24-bit audio data.
diff -Nru a/docs/afIntro b/docs/afIntro
--- a/docs/afIntro	2004-06-14 03:29:27 -07:00
+++ b/docs/afIntro	2004-06-14 03:29:27 -07:00
@@ -41,8 +41,8 @@
 The current Audio File Library does not support the concept of a virtual
 sampling rate, but this may be supported in the future.
 
-At the present, the Audio File Library supports only CCITT G.711
-mu-law/A-law compression.
+At present the Audio File Library supports CCITT G.711 mu-law and A-law
+compression as well as IMA and MS ADPCM compression.
 
 PROGRAMMING PARADIGM
 
diff -Nru a/docs/afReadFrames b/docs/afReadFrames
--- a/docs/afReadFrames	2004-06-14 03:29:27 -07:00
+++ b/docs/afReadFrames	2004-06-14 03:29:27 -07:00
@@ -30,16 +30,11 @@
 ERRORS
 
 Possible errors include
-(old school)
 AF_BAD_READ
 AF_BAD_FILEHANDLE
 AF_BAD_LSEEK
 AF_BAD_TRACKID (the track parameter differs from AF_DEFAULT_TRACK)
 AF_BAD_AIFF_SSND
-
-(new school--unsupported)
-AF_ERR_BAD_READ
-AF_ERR_BAD_LSEEK
 
 SEE ALSO
 
diff -Nru a/docs/afSetVirtualByteOrder b/docs/afSetVirtualByteOrder
--- a/docs/afSetVirtualByteOrder	2004-06-14 03:29:27 -07:00
+++ b/docs/afSetVirtualByteOrder	2004-06-14 03:29:27 -07:00
@@ -30,9 +30,7 @@
 
 * sampleFormat is an integer which denotes a virtual sample format.
   Valid values are AF_SAMPFMT_TWOSCOMP, AF_SAMPFMT_UNSIGNED,
-  AF_SAMPFMT_FLOAT, and AF_SAMPFMT_DOUBLE.  Note that this
-  implementation of the Audio File Library only supports the two's
-  complement sample format at present.
+  AF_SAMPFMT_FLOAT, and AF_SAMPFMT_DOUBLE.
 
 * sampleWidth is a positive integer which specifies the number of bits in a
   virtual sample.
